<!DOCTYPE html>
<html>
<head>
<title>COMPONENT PROPERTY SYNTAX</title>
<link rel="stylesheet" type="text/css" href="xschem_man.css" />
<style type="text/css">
/* Local styling goes here */
p{padding: 15px  30px 10px;}

</style>

</head>
<body>

<!-- start of slide -->
<div class="content">   
<!-- navigation buttons -->
<a href="symbol_property_syntax.html" class="prev">PREV</a>
<a href="xschem_man.html" class="home">UP</a>
<a href="creating_schematic.html" class="next">NEXT</a>
 <!-- slide title -->
 <h1>COMPONENT PROPERTY SYNTAX</h1><br>
 <p>
  Component property strings can be set in the usual way with the <kbd>'q'</kbd> on a selected
  component instance or by menu <kbd>Properties&nbsp;--&gt;&nbsp;Edit</kbd>
 </p> 
 <img src="component_properties.png">
 <p>
  The dialog box allows to change the property string as well as the symbol reference. The property string
  is essentially a list of <kbd>attribute=value</kbd> items. As with symbol properties if a <kbd>value</kbd>
  has white space it should be double-quoted.
  The following property definitions are identical:
 </p>
 <pre class=code>
name=mchanged_name model=nmos w=20u l=3u m=10
 </pre><br>
 <pre class=code>
name="mchanged_name" model="nmos" w="20u" l="3u" m="10"
 </pre><br>
 <p> 
  Given the role of the <kbd>"</kbd> character, if quoted values are needed escapes must be used, like in 
  the following example where the model name will be with quotes in netlist:
 </p>
 <pre class=code>
name="mchanged_name" model="\"nmos\"" w="20u" l="3u" m="10"
 </pre>
 <p>or</p>
 <pre class=code>
name="mchanged_name" model=\"nmos\" w="20u" l="3u" m="10"
 </pre>
 <p>
  the resulting SPICE netlist will be:<br>
  <kbd>mchanged_name DRAIN GATE SOURCE BODY "nmos" w=20u l=3u m=10</kbd>
 </p>
 <p> 
  There is no limit on the number of <kbd>attribute=value</kbd> items, each attribute should have a corresponding 
  <kbd>@attribute</kbd> in the symbol definition format, but this is not a requirement. There are a number
  of special attributes as we will see later.
 </p>
 <p class="important"> 
  Important: a <kbd>name=&lt;inst_name&gt;</kbd> item is mandatory and must be placed  
  in component property string to get a valid netlist, as this is the partname or so-called refdes (reference designator).
  If <kbd>&lt;inst_name&gt;</kbd> is already used in another component XSCHEM will
  auto-rename it to a unique name preserving the first letter (which ts a device type indicator
  for SPICE like netlists).
 </p>
 <h3>PREDEFINED COMPONENT ATTRIBUTES</h3>
 <ul>
  <li><kbd>name</kbd></li>
  <p> This defines the name of the instance. 
    Names are unique, so if for example multiple MOS components are
    placed in the design one should be named <kbd>m1</kbd> and the second <kbd>m2</kbd> or anything 
    else, provided the names are different. XSCHEM enforces this, 
    unless <kbd>Options -&gt; allow duplicated instance names</kbd> is set. If a name is given that already
    exist in the current schematic it will be renamed. Normally the template string defines a default
    name for a given component, and expecially for SPICE compatibility, the first character must NOT 
    be changed. For example, the default name for a MOS transistor is <kbd>m1</kbd>, it can be renamed
    for example to <kbd>mcurr_source</kbd> but not for example to <kbd>dcurr_source</kbd>. XSCHEM 
    does not enforce that the first character is preserved, it's up to the designer to keep it 
    consistent with the component type.</p>
  <li><kbd>embed</kbd></li>
  <p>
   When the <kbd>embed=true</kbd> is set on a component instance
   the corresponding symbol will be saved into the schematic (.sch) file on the next save operation.
   This allows to distribute schematic files that contain the used symbols so these
   will not depend on external library symbols.
   When this attribute is set on a component instance, all instances in the schematic referring to the same 
   symbol will use the embedded symbol definition.
   When descending into an embedded symbol, any changes will be local, meaning that no library symbol
   will be affected. The changes will be saved using the embedded tag (<kbd>[...]</kbd>) into the
   schematic file.
   Removing this attribute will revert to external symbols after saving and reloading the schematic file.

  </p>
  <li><kbd>url</kbd></li>
  <p> This attribute defines a location (web page, file) that can be viewed when hitting the
    <kbd>&lt;shift&gt;H</kbd> key (or <kbd>&lt;Alt&gt; left mouse buttoni</kbd>) on a selected component. 
    This is very useful to link a datasheet to a
    component, for example. The default program used to open the url is <kbd>xdg-open</kbd>. 
    this can be changed in the <kbd>~/xschemrc</kbd> configuration file with the <kbd>launcher_default_program</kbd>
    variable.
    <kbd>url</kbd> can be an http link or a local file that has a default association known to xdg-open.</p>
  <li><kbd>program</kbd></li>
  <p> this attribute can be used to specify an application to be used to open the <kbd>url</kbd> link,
      if the default application has to be changed or the file type is unknown.
      for example <kbd>program=evince</kbd> may be given to specify an application for a pdf file
      specified with <kbd>url</kbd></p>
  <li><kbd>tclcommand</kbd></li>
  <p> this can be any tcl statement (or group of statements separated by semicolons) including all xschem-specific
      commands, the statement will be executed when pressing the <kbd>&lt;shift&gt;H</kbd> key 
      (or <kbd>&lt;Alt&gt; left mouse button</kbd>) on the selected instance.
      <br>The <kbd>tclcommand</kbd> and <kbd>url</kbd> properties are mutually exclusive.</p>
  <img src="component_properties3.png">
  <li><kbd>only_toplevel</kbd></li>
  <p>this attribute is valid only on <kbd>netlist_commands</kbd> type symbols and specifies that the 
    symbol should be netlisted only if it is instantiated in the top-most hierarchy. This is very usefull
    for spice commands. Spice commands are placed in a special <kbd>netlist</kbd> component as we will see
    and are meaningfull only when simulating the block, but should be skipped if the component
    is simulated as part of a bigger system which has its own (at higher hierarchy level)
    <kbd>netlist</kbd>component for Spice commands.</p>
  <img src="component_properties0.png">
  <li><kbd>lock</kbd></li>
  <p> A <kbd>lock=true</kbd> attribute will make the symbol not editable. the only way to make it editable again is 
      to double click on it to bring up the edit attributes dialog box and set to false. This is useful for title
      symbols. </p>
  <li><kbd>hide</kbd></li>
  <p> A <kbd>hide=true</kbd> attribute will only display the symbol bounding box.</p>
  <li><kbd>hide_texts</kbd></li>
  <p> A <kbd>hide_texts=true</kbd> attribute will hide all symbol texts.</p>
  <li><kbd>text_size_&lt;n&gt;</kbd></li>
  <p> This attribute sets the size of symbol text item number <kbd>n</kbd>. This allows
   instance based symbol text sizing.</p>
  <li><kbd>highlight</kbd></li>
  <p>If set to <kbd>true</kbd> the symbol will be highlighted when one of the nets attached to its pins are highlighted.</p>
  <li><kbd>net_name</kbd></li>
  <p>If set to <kbd>true</kbd> the <kbd>#n:net_name</kbd> symbol attributes will display the net names attached to pin terminals.
     the <kbd>n</kbd> is a pin number or name.</p>
  <li><kbd>place</kbd></li>
  <p>The <kbd>place=end</kbd> attribute is only valid only for <kbd>netlist_commands</kbd> type symbols, and tells
    XSCHEM that this component must be netlisted last. This is necessary for some spice commands 
    that need to be placed <b>after</b> the rest of the netlist.</p>
  <p>The <kbd>place=header</kbd> attribute is only valid only for <kbd>netlist_commands</kbd> type symbols 
     and spice netlisting mode, it tells XSCHEM that this component must be netlisted in the very first
     part of a spice netlist. This is necessary for some spice commands 
     that need to be placed <b>before</b> the rest of the netlist.</p>

  <li id="spice_ignore"><kbd>vhdl_ignore</kbd></li>
  <li><kbd>spice_ignore</kbd></li>
  <li><kbd>verilog_ignore</kbd></li>
  <li><kbd>tedax_ignore</kbd></li>
  <p >These 4 attributes tell XSCHEM to ignore completely the instance in the respective netlist formats.
    Allowed values for these attributes are <kbd>true</kbd> (or <kbd>open</kbd>), <kbd>false</kbd> and
    <kbd>short</kbd>
    If <kbd>short</kbd> is specified the instance will short together all its pins. For this to work
    only one of the nets connected to the symbol may have a net label attached to it. All other nets will take this name.
    If more labeled nets connect to the shorted symbol a net short error is reported.
    Shorted instances are displayed in the pin color (red) layer. See in below image the upper netname of R1
    is <kbd>VDD</kbd>. </p>
  <img src="component_properties4.png">
  <p> Disabled components (<kbd>spice_ignore=true</kbd> or <kbd>spice_ignore=open</kbd>) are displayed in grey.</p>
  <img src="component_properties5.png">

  <li><kbd>lvs_ignore</kbd></li>
  <p> This attribute works in the same way as above attributes, may take the values 
   <kbd>true</kbd> (or <kbd>open</kbd>), <kbd>false</kbd> or <kbd>short</kbd>, and
   will affect the specific instance behaviour in the same way, but only if tcl variable
   <kbd>lvs_ignore</kbd> is set to <kbd>1</kbd>. This can be done in the Simulation menu:
   <kbd>Set 'lvs_ignore' variable</kbd>. If this <kbd>lvs_ignore</kbd> is set on the instance
   it will be shorted / ignored or kept as is depending on its <kbd>lvs_ignore</kbd> attribute
   and will be effective in all netlising formats. This is mostly used to modify the produced netlist
   automatically when doing schematic vs layout (LVS) comparison.</p>

  <p> By using the <kbd>*_ignore</kbd> attributes you can modify the circuit depending on the value of a tcl variable:</p>
  <img src="component_properties6.png">
  <p> just set the attribute to something like:</p>
  <pre class="code"> spice_ignore="tcleval([if {$IGNORE == 1} {return {true}} else {return {false}}])" </pre>
  <p> or:</p>
  <pre class="code"> spice_ignore="tcleval([if {$IGNORE == 1} {return {short}} else {return {false}}])" </pre><br>

  <li><kbd>spice_sym_def</kbd></li>
  <li><kbd>verilog_sym_def</kbd></li>
  <li><kbd>vhdl_sym_def</kbd></li>
  <p> If any of these attributes are present and not empty and the symbol type is set to <kbd>subcircuit</kbd>
   the corresponding netlister will ignore the schematic subcircuit for this specific instance
   and dump into the netlist the content of this attribute.
   This attribute must be paired with a <kbd>schematic=...</kbd> attribute set on the instance that tells
   the subcircuit name to use for this particular instance.
   The typical usage is to include a file, example:<br>
  <pre class="code">
    verilog_sym_def="tcleval(`include \"[abs_sym_path verilog_include_file.v]\")"
  </pre>
  </p> 
  <p>
   In this example a <kbd>verilog_include_file.v</kbd> is included using the verilog <kbd>`include</kbd> directive.
   In order to generate a full path for it the <kbd>abs_sym_path</kbd> TCL function is used that searches for this file
   in any of the <kbd>XCHEM_LIBRARY_PATH</kbd> directories. Since TCL is used the attribute is wrappend into a tcleval(...),<br>
   The following will appear in the generated netlist:
   <pre class="code">
// expanding   symbol:  verilog_include.sym # of pins=3 
// sym_path: /home/schippes/.xschem/xschem_library/verilog_include.sym
`include "/home/schippes/.xschem/xschem_library/verilog_include_file.v"
   </pre>
  </p>



  <li><kbd>sig_type</kbd></li>
  <p> For VHDL type netlist, this tells that the current label names a signal (or constant) of
    type <kbd>sig_type</kbd>. For example a label can be placed with name <kbd>TEST</kbd> and 
    <kbd>sig_type=BIT</kbd>. The default type for VHDL if this property is missing  is <kbd>std_logic</kbd>.
    The following picture shows the usage of <kbd>sig_type</kbd> and the resulting VHDL netlist.
    This property is applicable only to <kbd>label</kbd> type components: <kbd>ipin.sym</kbd>, 
    <kbd>iopin.sym</kbd>, <kbd>opin.sym</kbd>, <kbd>lab_pin.sym</kbd>, <kbd>lab_wire.sym</kbd>.
  </p>
  <img src="component_properties1.png">
  <li><kbd>verilog_type</kbd></li>
  <p>This is the same as sig_type but for verilog netlisting: can be used to declare a <kbd>wire</kbd>
     or a <kbd>reg</kbd> or any other datatype supported by the verilog language.
  </p>
  <li><kbd>generic_type</kbd></li>
  <p><kbd>generic_type</kbd> defines the type of parameters passed to VHDL components.
    Consider the following examples of placement of <kbd>generic_pin</kbd> components in a 
    VHDL design: 
  </p>
  <img src="component_properties2.png">
  <p> As you will see in the <a href="parameters.html">parameters</a> slide, generics (they are just
    parameters passed to components) can be passed also via property strings in addition to using 
    <kbd>generic_pin</kbd> components.</p>
   
  <li><kbd>class</kbd></li>
  <p>The <kbd>class</kbd> attribute is used to declare the class of a VHDL signal, most used classes are
    <kbd>signal</kbd> and <kbd>constant</kbd>. Default if missing is <kbd>signal</kbd>.</p>
  <li><kbd>device_model</kbd></li>
  <p>
   This attribute contains a SPICE .model or .subckt specification (<kbd>device_model=".model D1N4148 D ...."</kbd>)
   that will be printed at end of netlist only once for the specified component (D1N4148 in the example).
   <kbd>device_model</kbd> attributes defined at instance level override the <kbd>device_model</kbd> set
   in the symbol if any.
  </p>

  <li><kbd>schematic</kbd></li>
  <p>
   This attribute specifies an alternate schematic file to open when descending into the subcircuit.
   This is done only for the specific instance allowing to differentiate implementation ona specific
   instance of a given subcircuit.
   The specified schematic must have the same interface (in/out/inout pins) as the base schematic (that
   is inferred from the symbol name).<br>
   Example: <kbd>schematic=sky130_tests/inv2.sch</kbd>
  </p>

  <li><kbd>pinnumber(name)</kbd></li>
  <p> This will override at instance level the value of attribute <kbd>pinnumber</kbd> of pin <kbd>name</kbd> of the symbol.
      This is mainly used for tedax, where by back annotation a connection to a symbol must be changed.</p>
  <li><kbd>pinnumber(index)</kbd></li>
  <p> This will override at instance level the value of attribute <kbd>pinnumber</kbd> of <kbd>index</kbd>th pin of the symbol.
      This is mainly used for tedax, where by back annotation a connection to a symbol must be changed.
      This notation is faster since xschem does not have to find a pin by string matching.</p>

  <li><kbd>pin_attr(name|index)</kbd></li>
  <p> This is a general mechanism where at instance level a pin attribute may be overridden for netlisting. Example:<br>
      <kbd> sig_type(OUT)=bit_vector</kbd> (set VHDL type of pin OUT to bit_vector).</p>
 </ul><br>

 <h3>TCL ATTRIBUTE SUBSTITUTION</h3>

  <p>
   Any attribute and symbol text can be embedded in a <kbd>tcleval(....)</kbd> construct, the string inside the
   parentheses will be passed to the tcl interpreter for evaluation. This allows to use any tcl 
   variable/command/expression. Example: <br>
  <kbd>value="tcleval([expr {[info exists ::resval] ? $::resval : {100k}}])"</kbd><br>
  this attribute will set <kbd>value</kbd> (example: value of a resistor) to 100k if global tcl variable
  <kbd>resval</kbd> is not set or to the value of <kbd>resval</kbd> if set.
  </p>


 <!-- end of slide -->
 <div class="filler"></div>
</div>

<!-- frame footer -->
<iframe seamless src="xschem_footer.html"  class="footer_iframe" >
</body>
</html>

